Working with Movie Time
Every QuickTime movie has its own time base. A movie's time base allows all the tracks that make up the movie to be synchronized when the movie is played. The Movie Toolbox provides a number of functions that allow your application to determine and establish the time parameters of a movie. This section discusses those functions. Later sections in this chapter discuss the Movie Toolbox functions that allow you to work with the time parameters of tracks and media structures. For a complete discussion of the relationships between movie, track, and media time parameters, see
"Introduction to Movies,"
. For information about more functions that work with time, see
"Time Base Functions,"
.
You can use the
GetMovieTimeBase
function to retrieve the time base for a movie.
You can work with a movie's current time by calling the
GetMovieTime
,
SetMovieTime
, and
SetMovieTimeValue
functions.
You can work with a movie's time scale by calling the
GetMovieTimeScale
and
SetMovieTimeScale
functions.
The Movie Toolbox can calculate the total duration of a movie. You can use the
GetMovieDuration
function to retrieve a movie's duration.
Your application can call the
GetMovieRate
and
SetMovieRate
to work with a movie's playback rate.
GetMovieDuration
The
GetMovieDuration
function returns the duration of a movie. The Movie Toolbox examines the durations of all the tracks of the movie to determine this value.
pascal TimeValue GetMovieDuration (Movie theMovie);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
DESCRIPTION
The
GetMovieDuration
function returns a time value. This time value indicates the movie's duration, and it is expressed in the movie's time scale.
You cannot set movie direction explicitly because it is calculated as being the maximum durations of all the tracks in the movie.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SetMovieTimeValue
The
SetMovieTimeValue
function allows your application to set a movie's time value. You specify the new time as a time value, rather than in a time structure. You must ensure that the time value is in the movie's time scale.
pascal void SetMovieTimeValue (Movie theMovie, TimeValue newTime);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
-
newTime
-
Specifies the movie's new time value. The Movie Toolbox interprets this time value relative to the movie's time scale. If you specify a value that is outside the duration of the movie, the Movie Toolbox sets the movie time to the beginning or end of the movie, as appropriate.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SEE ALSO
You can also set a movie's current time by calling the
SetMovieTime
function, which is described in the next section. This function requires that you specify the new time value in a time structure.
SetMovieTime
The
SetMovieTime
function allows your application to change a movie's current time. You must specify the new time in a time structure. The Movie Toolbox saves the movie's current time when you save the movie.
pascal void SetMovieTime (Movie theMovie,
const TimeRecord *newTime);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
-
newTime
-
Contains a pointer to a time structure. If you specify a value that is outside the duration of the movie, the Movie Toolbox sets the movie time to the beginning or end of the movie, as appropriate.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SEE ALSO
You can use the
SetMovieTimeValue
function, described in the previous section, to change a movie's current time without specifying a time structure.
You can retrieve a movie's current time value by calling the
GetMovieTime
function, which is described in the next section.
GetMovieTime
The
GetMovieTime
function returns a movie's current time. This function returns the time in two formats: as a time value and in a time structure.
pascal TimeValue GetMovieTime (Movie theMovie,
TimeRecord *currentTime);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
-
currentTime
-
Contains a pointer to a time structure. The
GetMovieTime
function updates this time structure to contain the movie's current time. If you do not want this information, set this parameter to
nil
.
DESCRIPTION
The
GetMovieTime
function returns a time value. This time value indicates the movie's current time, and it is expressed in the movie's time scale.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SEE ALSO
You can set a movie's current time by calling the
SetMovieTime
or
SetMovieTimeValue
functions, which are described on
SetMovieTime
and
SetMovieTimeValue
, respectively.
SetMovieRate
The
SetMovieRate
function sets a movie's playback rate.
pascal void SetMovieRate (Movie theMovie, Fixed rate);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
-
rate
-
Specifies the new movie rate as a 32-bit, fixed-point number. Positive integers indicate forward rates and negative integers indicate reverse rates.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SEE ALSO
Your application can retrieve a movie's current playback rate by calling the
GetMovieRate
function, which is described in the next section. To play a movie at the movie's preferred rate from a position stored within the movie, you can use the
StartMovie
function (described on
StartMovie
).
GetMovieRate
The
GetMovieRate
function returns a movie's playback rate.
pascal Fixed GetMovieRate (Movie theMovie);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
DESCRIPTION
The
GetMovieRate
function returns the movie rate as a 32-bit, fixed-point number. Positive integers indicate forward rates and negative integers indicate reverse rates.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SEE ALSO
Your application can set the movie's playback rate by calling the
SetMovieRate
function, which is described in the previous section.
SetMovieTimeScale
The
SetMovieTimeScale
function establishes a movie's time scale.
pascal void SetMovieTimeScale (Movie theMovie,
TimeScale timeScale);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
-
timeScale
-
Specifies the movie's new time scale.
DESCRIPTION
In response to this request, the Movie Toolbox adjusts the edit list of the movie's tracks so that movie playback is unaffected. If you change a movie's time scale by setting it to a smaller value (thereby losing precision in the movie's time values), the Movie Toolbox may edit information from the movie. In general, you should only increase the time scale value, and you should try to use integer multiples of the existing time scale.
SPECIAL CONSIDERATIONS
Do not call
SetMovieTimeScale
if you have edited your movie. This function quantizes the beginning and the end of the edits to the new units. Therefore, if you do not use an integral multiple, the position of your edits may change.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SEE ALSO
You can retrieve a movie's time scale by calling the
GetMovieTimeScale
function, which is described in the next section.
GetMovieTimeScale
The
GetMovieTimeScale
function returns the time scale of a movie.
pascal TimeScale GetMovieTimeScale (Movie theMovie);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
DESCRIPTION
The default QuickTime movie time scale is 600 units per second; however, this number may change in the future. The default time scale was chosen because it is convenient for working with common video frame rates of 30, 25, 24, 15, 12, 10, and 8.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
SEE ALSO
You can set a movie's time scale by calling the
SetMovieTimeScale
function, which is described in the previous section.
GetMovieTimeBase
The
GetMovieTimeBase
function returns a movie's time base.
pascal TimeBase GetMovieTimeBase (Movie theMovie);
-
theMovie
-
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
(described on
NewMovie
,
NewMovieFromFile
, and
NewMovieFromHandle
, respectively).
DESCRIPTION
You cannot use the returned time base value with the Movie Toolbox's
SetTimeBaseMasterTimeBase
and
SetTimeBaseMasterClock
functions (described on
SetTimeBaseMasterTimeBase
and
SetTimeBaseMasterClock
, respectively). Use the
SetMovieMasterTimeBase
and
SetMovieMasterClock
functions (described on
SetMovieMasterTimeBase
and
SetMovieMasterClock
, respectively) instead.
The Movie Toolbox disposes of a movie's time base when you dispose of the movie.
SPECIAL CONSIDERATIONS
Do not dispose of the
TimeBase
result returned by the
GetMovieTimeBase
function as it is owned by the movie.
ERROR CODES
|
invalidMovie
|
-2010
|
This movie is corrupted or invalid
|
© 1999 Apple Computer, Inc.Previous | Overview | Contents | Next
